Format strings

Format strings define how the requested data will be printed using either a one-character format code or customized printf formats.

One-character format codes

The one-character format provides a simple method for defining how to print out the requested data. The table below shows the available one-character conversion codes and the resulting output for a data request that retrieves the value 334.1688 mm.

Note: Codes a, b, c, and d also print "mm" if the default unit is not millimeters; this ensures that the output values can also be read back in correctly.
Codes that print inches always print the units: ' or ".

Customized printf formats

The format string C U cform can be used when the required output format cannot be achieved with One-character format codes.

The string is written without any spaces and consists of the following elements:

  • C is a control digit that defines rounding and whether to print the unit:

    • 0 – normal rounding, no unit

    • 1 – normal rounding, unit printed

    • 2 – rounding upwards, no unit

    • 3 – rounding upwards, unit printed

  • U selects the unit of the printed value from the quantity definition table, counting from 0.

    For example, if the quantity is diameter, then U=0 selects millimeters, U=1 selects meters, U=2 selects inches, and U=3 selects feet.

    ID

    Description

    Number of units

    Unit 0

    Conversion

    Unit 1

    Conversion

    Unit 2

    Conversion

    Unit3

    Conversion

    2

    Diam

    4

    mm

    1.0

    m

    1000.0

    "

    25.4

    '

    304.8

  • cform is a valid C language printf format for a floating point number.

The table below shows some examples of format strings and the resulting output for an internal length value of 334.1688 mm, when the quantity type ID is 3 (length). Quantities are assumed to be defined according to table Quantity Definitions Table.

Note: The accuracy of floating point numbers in computers is normally about seven digits. This means that for large numbers the decimals may not be accurate even though they are output.

C language printf format

C language printf format means here the control string used in the C printf() function. A control string may or may not contain conversion specifications. A conversion specification begins with a % character and ends with a conversion character.

  • c – single character

  • d – decimal integer

  • e – floating point number in scientific notation

  • f – floating point number

  • g – the e format or f format (whichever is shorter)

  • s – string of characters

The conversion specification will be replaced by some internal value on output. For example, if a floating point value (assumed here to be 987.654321) is to be printed we could define the control string as "Value is: %.2f"; the string would be printed as: "Value is: 987.65". The string %.2f is the conversion specification for a float number with 2 digits after the decimal point; the rest of the format string is copied unchanged to the output.

Between the % sign and the conversion character there may be a minus sign, digit, or period-digit (in this order); any combination of these characters may be present or absent.

  • A minus sign means that the converted argument is to be left-adjusted in its field. If there is no minus sign the argument will be right-adjusted.

  • A digit or digit string defines the field width of the converted argument. If the converted argument has fewer digits than the specified field width then it will be padded with blanks. If the field width is less than the number of characters of the converted argument then the field will be expanded to whatever is needed.

  • A period followed by a digit gives the precision. For "e" and "f" conversions this is the number of digits to the right of the decimal point. For "s" conversion it is the maximum number of characters to be printed from a string.

You can find are some examples in the table below:

DATE and TIME formats

For DATE conversions (when r2 =  -2), this field contains a one-digit code that converts target data into the following date formats:

  • 0,  mm/dd/yy

  • 1,  dd.mm.yy

  • 2, dd-mm-yy

  • 3, mm/dd/yyyy

  • 4, dd.mm.yyyy

  • 5, default format, dd-mm-yyyy

  • 6, yyyy/mm/dd

  • 7, yyyy-mm-dd

For TIME conversions (when r2 =  -3), this field contains a one-digit code that converts target data into the following time formats:

  • 0, hh:mm

  • 1, hh:mm:ss

  • 2, hh.mm

  • 3 hh.mm.ss

For example, the Plant Modeller tag "mot" (modification time) can be converted to a human-readable format using the following data requests:

mot; -2;0; /* output date as mm/dd/yy */

mot; -3;0; /* output time as hh:mm */